home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / program / janus11.zip / JANUS.DOC < prev    next >
Text File  |  1996-04-19  |  20KB  |  679 lines
  1.  
  2.  
  3.                    ████┐ ███████┐ ██████┐ ██┐ ██┐  ██┐ ███████┐                 
  4.                    └██┌┘ ██┌──██│ ██┌─██│ ██│ ██│  ██│ ██┌────┘                 
  5.                     ██│  ███████│ ██│ ██│ ██│ ██│  ██│ ███████┐                 
  6.                 ██  ██│  ██┌──██│ ██│ ██│ ██│ ██│  ██│ └────██│                 
  7.                 ██████│  ██│  ██│ ██│ ██████│ ███████│ ███████│                 
  8.                 └─────┘  └─┘  └─┘ └─┘ └─────┘ └──────┘ └──────┘                 
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                  Borland C Programmer's Communications Library
  15.  
  16.  
  17.  
  18.                            (c)1994 Servile Software
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25. 2
  26. INTRODUCTION:
  27. ~~~~~~~~~~~~~
  28.  
  29. Software for use with local computers receive their input from the user by way 
  30. of the keyboard functions included with the development language and display 
  31. output to the user through the video functions also supplied with the 
  32. development language. Remote computer access through the serial port requires 
  33. that user input comes from functions not supplied with the development 
  34. language, and the same is true of output functions which must send information 
  35. to the user by way of the serial port. Janus provides additional functions for 
  36. your Borland C development language which allow remote keyboard input, and 
  37. remote video display to occur. 
  38.  
  39. To further assist with the writing of BBS doors Janus also includes an 
  40. automatic process for reading the caller information files created by many BBS 
  41. packages; DOOR.SYS and DOORINFO?.DEF. Janus defines global variables which 
  42. record caller information provided by the BBS package; The caller's name, 
  43. location, telephone numbers and so on. Janus also provides global variables 
  44. which record information about the connection; baud speed, data bits, the 
  45. terminal emulation in use and so on. 
  46.  
  47. Janus takes care of monitoring the connection and terminates the program 
  48. automatically should the connection be lost, or the caller's connection time 
  49. exceeds that which is allowed (as defined by the host BBS setup). 
  50.  
  51.  
  52. SHAREWARE NOTICE:
  53. ~~~~~~~~~~~~~~~~~
  54.  
  55. Janus is supplied in small memory model only for shareware evaluation 
  56. purposes. The library is fully functional and differs from the registered 
  57. version only in displaying a shareware notice upon exit, and delaying two 
  58. seconds so that you and your callers can read the message.
  59.  
  60. The registered version includes small, medium, compact and large memory models 
  61. without the shareware notice and three second delay on leaving the door.
  62.  
  63.  
  64. TUTORIAL:
  65. ~~~~~~~~~
  66.  
  67. There are a few basic principles which must be grasped before you can make use 
  68. of Janus. Firstly, Janus provides additional functions which enhance your 
  69. Borland C development language to allow you to accept input from a remote 
  70. operator through the serial port, and enable you to send output to the remote 
  71. caller. In order to do this the Janus functions require that the program is 
  72. running on an IBM PC or compatible computer and that a FOSSIL driver is 
  73. installed in memory. Program's written and making use of Janus's extra 
  74. functions will work fine locally without a loaded FOSSIL driver, but for 
  75. remote access it is essential. 
  76.  
  77. Before your program calls any Janus functions the remote capabilities must be 
  78. initialised - the door opened - this is achieved with a call to the Janus 
  79. function j_open_door(). This function takes a single character string 
  80. parameter. This parameter specifies the full path and name of the BBS drop 
  81. file to be read by Janus. If you specify a null string - "" - Janus will 
  82. search the current DOS directory for a file called "DOOR.SYS" and if it fails 
  83. to find that "DORINFO?.DEF" where the ? is any character. 
  84.  
  85. 3
  86. Before the Janus enganced program terminates back to the BBS or DOS, it must 
  87. de-initialise - close the door - and this is achieved by the Janus function 
  88. j_close_door(). It is recommended that you make use of the Borland C atexit() 
  89. function to ensure that the required functions are called when the program 
  90. terminates as Janus can terminate from within its own functions. 
  91.  
  92. The process is simply:
  93.  
  94.         1 open door
  95.         2 do program
  96.         3 close door
  97.         4 return
  98.  
  99.  
  100. The following source code describes an extremely simple door program. The 
  101. program displays a welcome message to the caller on both the caller's (remote) 
  102. screen and on the sysop's (local) screen. Notice the inclusion of the header 
  103. file "JANUS.H". 
  104.  
  105. /*
  106.     A very simple door
  107. */
  108.  
  109. #include <stdio.h>
  110. #include <stdlib.h>
  111. #include <string.h>
  112.  
  113. #include "janus.h"       /* Prototypes and global variable definitions */
  114.  
  115. main(int argc, char **argv)
  116. {
  117.     strcpy(program_name,"SIMPLE DOOR");      /* Initialise program name */
  118.  
  119.     if (argc > 1)
  120.         j_open_door(argv[1]);               /* Initialise with drop file */
  121.     else
  122.         j_open_door("");                    /* Initialise */ 
  123.     atexit(j_close_door);                   /* 
  124.                                                  Ensure the door is
  125.                                                  de-initialised on exit
  126.                                              */
  127.     j_printf("\r\nHello %s",username);      /* Print to terminals */ 
  128.  
  129.     return;
  130. }
  131.  
  132.  
  133. NAMING CONVENTIONS:
  134. ~~~~~~~~~~~~~~~~~~~
  135.  
  136. Janus functions are named as similarly to the Borland C local equivalents as 
  137. possible, but are prefixed "j_" thus j_printf() is a remote variation on 
  138. printf().
  139.  
  140. Libraries are prefixed JANUS followed by a letter indicating the memory model; 
  141. S,M,C or L. The small memory model library is named "JANUSS.LIB"
  142.  
  143.  
  144.  
  145. 4
  146. INPUT FUNCTIONS:
  147. ~~~~~~~~~~~~~~~~
  148.  
  149. Just as C provides several functions for receiving input from the local 
  150. keyboard, so Janus provides several functions for receiving input from the 
  151. remote caller. All Janus functions check for the presence of a carrier and 
  152. keyboard time out and will terminate the program should the caller hang-up, 
  153. not press a key within the allotted time or if the caller's on-line time is 
  154. exceeded. 
  155.  
  156.  
  157. j_inkey()
  158.  
  159. Waits for a key press from either the local or remote terminal and returns an 
  160. unsigned char of the key code without echoing the character to the screen. 
  161. Equivalent to the C getch() function. 
  162.  
  163.  
  164. j_iskey()
  165.  
  166. Checks for a waiting key press from either the local or remote terminal and 
  167. returns non-zero if a key is available. The key code may be read with 
  168. j_inkey(). Unlike j_inkey() this function does not wait for a key to be 
  169. pressed, and so may be used within a loop to check if input is arriving from 
  170. either the caller or the sysop. 
  171.  
  172.  
  173. j_input(length, password, caps, hot, type);
  174.  
  175. j_input() is a general-purpose input function. It returns a pointer to a 
  176. string, and is used with strcpy(). 
  177.  
  178. The parameters are all single byte. The first parameter, 'length', specifies 
  179. the maximum number of characters which may be entered into the string. If the 
  180. 'password' parameter is non-zero, dots will echo the input, otherwise the 
  181. input characters will be echoed to both the local and remote terminals. 
  182.  
  183. if the 'caps' parameter is non-zero, input will be forced to CAPITALS.
  184.  
  185. If the 'hot' parameter is non-zero, the function doesn't wait for a carriage-
  186. return to be pressed, it returns when 'length' bytes have been entered. 
  187.  
  188.  
  189. The final parameter, 'type', specifies the behaviour of j_input() as 
  190. illustrated in the following table:
  191.  
  192.  
  193.         TYPE            ALLOWABLE INPUT CHARACTERS
  194.  
  195.           1             Any printable character
  196.  
  197.           2             Letters (A-Z) plus space only
  198.  
  199.           3             Digits (0-9) only
  200.  
  201.           4             Letters (A-Z) plus digits (0-9) and space only
  202.  
  203.           5             Y and N only
  204.  
  205.           6             Name input. Only allows letters (A-Z), space and hyphen.
  206. 5
  207.                         First character must be letter
  208.                         Maximum of one space
  209.                         First letter of each word capitalised
  210.  
  211.           7             Neat input. Only allows letters (A-Z), digits (0-9) and
  212.                         space.
  213.                         Fi